home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3p / usctlsema.z / usctlsema
Encoding:
Text File  |  1998-10-20  |  9.9 KB  |  199 lines
  1.  
  2.  
  3.  
  4. UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))                                                    UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      usctlsema - semaphore control operations
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<uuuulllloooocccckkkkssss....hhhh>>>>
  13.  
  14.      iiiinnnntttt uuuussssccccttttllllsssseeeemmmmaaaa ((((uuuusssseeeemmmmaaaa____tttt ****sssseeeemmmmaaaa,,,, iiiinnnntttt ccccmmmmdddd [[[[,,,, vvvvooooiiiidddd ****aaaarrrrgggg ]]]]))));;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      _u_s_c_t_l_s_e_m_a provides a variety of semaphore control operations as specified
  18.      by _c_m_d.  The following _c_m_d_s are available:
  19.  
  20.      CCCCSSSS____MMMMEEEETTTTEEEERRRROOOONNNN     Enable metering for the semaphore specified by _s_e_m_a.  The
  21.                     metering information gathered consists of the number of
  22.                     _u_s_p_s_e_m_a and _u_s_c_p_s_e_m_a calls, the number of times the
  23.                     semaphore could immediately be acquired, the number of
  24.                     _u_s_v_s_e_m_a calls, the number of times _u_s_v_s_e_m_a was called and
  25.                     no process was queued waiting, the current number of
  26.                     processes waiting on the semaphore, and the maximum number
  27.                     of processes ever waiting on the semaphore.  All metering
  28.                     is stored in a _s_e_m_a_m_e_t_e_r__t structure defined in the header
  29.                     file <_u_l_o_c_k_s._h> and described below.
  30.  
  31.      CCCCSSSS____MMMMEEEETTTTEEEERRRROOOOFFFFFFFF    Disable metering for the semaphore specified by _s_e_m_a.
  32.  
  33.      CCCCSSSS____MMMMEEEETTTTEEEERRRRFFFFEEEETTTTCCCCHHHH  Fills the structure pointed to by _a_r_g with the metering
  34.                     data associated with _s_e_m_a.
  35.  
  36.      CCCCSSSS____MMMMEEEETTTTEEEERRRRRRRREEEESSSSEEEETTTT  Reinitializes the _s_e_m_a_m_e_t_e_r__t structure associated with
  37.                     _s_e_m_a to all 0.
  38.  
  39.      CCCCSSSS____DDDDEEEEBBBBUUUUGGGGOOOONNNN     Enable debug monitoring for the semaphore specified by
  40.                     _s_e_m_a.  The debugging information maintained consists of
  41.                     the process id of the owner of the semaphore, and the
  42.                     address in the owner process where the call to the
  43.                     semaphore operation was made, the process id of the last
  44.                     process to operate on the semaphore, and the address in
  45.                     the last process where the call to the semaphore operation
  46.                     was made.  The pid is set to -1 if no one owns the
  47.                     semaphore.  All debug info is stored in a _s_e_m_a_d_e_b_u_g__t
  48.                     structure defined in the header file <_u_l_o_c_k_s._h> and
  49.                     described below.
  50.  
  51.      CCCCSSSS____DDDDEEEEBBBBUUUUGGGGOOOOFFFFFFFF    Disable debugging for the semaphore specified by _s_e_m_a.
  52.  
  53.      CCCCSSSS____DDDDEEEEBBBBUUUUGGGGFFFFEEEETTTTCCCCHHHH  Fills the structure pointed to by _a_r_g with the debugging
  54.                     data associated with _s_e_m_a.
  55.  
  56.      CCCCSSSS____DDDDEEEEBBBBUUUUGGGGRRRREEEESSSSEEEETTTT  Reinitializes the elements of the _s_e_m_a_d_e_b_u_g__t structure
  57.                     associated with _s_e_m_a to values of -1.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))                                                    UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))
  71.  
  72.  
  73.  
  74.      CCCCSSSS____HHHHIIIISSSSTTTTOOOONNNN      Enable history logging for the semaphore specified by
  75.                     _s_e_m_a.  A global history is maintained that consists of a
  76.                     record of each transaction on semaphores in hhhhiiiisssstttt____tttt
  77.                     structures defined in the header file <_u_l_o_c_k_s._h>.  This is
  78.                     discussed further in _u_s_c_o_n_f_i_g(3P), which is used to
  79.                     retrieve history of semaphore transactions.
  80.  
  81.      CCCCSSSS____HHHHIIIISSSSTTTTOOOOFFFFFFFF     Disable history for the semaphore specified by _s_e_m_a.
  82.  
  83.      CCCCSSSS____RRRREEEECCCCUUUURRRRSSSSIIIIVVVVEEEEOOOONNNN Enables recursive acquires of the semaphore specified by
  84.                     _s_e_m_a.  Normally, an attempt to recursively acquire a
  85.                     mutual exclusion semaphore, (one initialized with a value
  86.                     of 1), will result in the calling process deadlocking.
  87.                     This option will cause a count to be incremented each time
  88.                     the current owner acquires the semaphore (including
  89.                     _u_s_c_p_s_e_m_a(3P)).  A matched number of _u_s_v_s_e_m_a(3P) calls will
  90.                     release the semaphore.  This option can be used only with
  91.                     mutual exclusion semaphores and must be specified when the
  92.                     semaphore is currently free.  Note that the recursive
  93.                     semaphore option is _nnnn_oooo_tttt _ssss_uuuu_pppp_pppp_oooo_rrrr_tttt_eeee_dddd for pthread applications
  94.                     intending to share the semaphore across process
  95.                     boundaries.  However, pthread application threads may use
  96.                     recursive semaphores when semaphore access is restricted
  97.                     to a single process.
  98.  
  99.      CCCCSSSS____RRRREEEECCCCUUUURRRRSSSSIIIIVVVVEEEEOOOOFFFFFFFF
  100.                     Disable recursive acquires of the semaphore specified by
  101.                     _s_e_m_a.
  102.  
  103.      Declarations of the function and _c_m_d_s, the hhhhiiiisssstttt____tttt structure, the
  104.      sssseeeemmmmaaaammmmeeeetttteeeerrrr____tttt structure, and the sssseeeemmmmaaaaddddeeeebbbbuuuugggg____tttt structure, are in the
  105.      <_u_l_o_c_k_s._h> header file.
  106.  
  107.      The structure declaration of sssseeeemmmmaaaammmmeeeetttteeeerrrr____tttt is:
  108.  
  109.         typedef struct semameter_s {
  110.                 int sm_phits;         /* number of immediate psemas*/
  111.                 int sm_psemas;        /* number of psema attempts */
  112.                 int sm_vsemas;        /* number of vsema attempts */
  113.                 int sm_vnowait;       /* number of vsemas with no one
  114.                                           waiting */
  115.                 int sm_nwait;         /* number of threads waiting on the
  116.                                           semaphore */
  117.                 int sm_maxnwait;      /* maximum number of threads waiting
  118.                                           on the semaphore */
  119.         } semameter_t;
  120.  
  121.      The structure declaration of sssseeeemmmmaaaaddddeeeebbbbuuuugggg____tttt is:
  122.  
  123.         typedef struct semadebug_s {
  124.                 int sd_owner_pid     /* the process that owns the semaphore */
  125.                 char * sd_owner_pc;  /* the address of last psema for
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))                                                    UUUUSSSSCCCCTTTTLLLLSSSSEEEEMMMMAAAA((((3333PPPP))))
  137.  
  138.  
  139.  
  140.                           process that owns the semaphore */
  141.                 int sd_last_pid;     /* the process that last did a p or v sema */
  142.                 char * sd_last_pc;   /* the address of the last routine to operate
  143.                                                on the semaphore */
  144.         } semadebug_t;
  145.  
  146.      _u_s_c_t_l_s_e_m_a will fail if one or more of the following are true:
  147.  
  148.      [EINVAL]       _c_m_d is not a valid command.
  149.  
  150.      [EINVAL]       _c_m_d is equal to CCCCSSSS____MMMMEEEETTTTEEEERRRRFFFFEEEETTTTCCCCHHHH and metering in not
  151.                     currently enabled.
  152.  
  153.      [EINVAL]       _c_m_d is equal to CCCCSSSS____DDDDEEEEBBBBUUUUGGGGFFFFEEEETTTTCCCCHHHH and debugging is not
  154.                     currently enabled.
  155.  
  156.      [ENOMEM]       _c_m_d is equal to CCCCSSSS____MMMMEEEETTTTEEEERRRROOOONNNN or CCCCSSSS____DDDDEEEEBBBBUUUUGGGGOOOONNNN and there was not
  157.                     enough memory in the arena.
  158.  
  159. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  160.      usconfig(3P), uscpsema(3P), usdumpsema(3P), usinitsema(3P),
  161.      usnewsema(3P), uspsema(3P), usvsema(3P).
  162.  
  163. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  164.      Upon successful completion, a value of 0 is returned. Otherwise, a value
  165.      of -1 is returned and _e_r_r_n_o is set to indicate the error.
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.